Stone Extension Library Release 1.0  Copyright ã1992 by Stone Design, Inc.  All Rights Reserved.

Camera

Inherits From:	N3DMovieCamera : N3DCamera : View : Responder : Object

Declared In:	SEL/Camera.h

Class Description

The Camera class augments and extends the N3DMovieCamera's (and N3DCamera's) hierarchy management and rendering capabilities.  This class is not designed to be subclassed-- the header and documentation are provided for developers working with the Stone Extensible Library.

This class (and Shape) have both a private and a public API-- all of the instance variables for the Camera class are documented  here, but not all of the methods (as the resourceful developer would soon discover with the aid of AppInspector).  Those methods that do not appear in this header are not for use by the developer;  either their implementation will change, or the support infrastructure hasn't been implemented to allow for it to be a part of public API.  Likewise, a number of the instance variables below have no documented API for querying or setting them-- this is usually because 3DReality has already provided a user interface for keeping track of those attributes.

Most of the methods that the SEL developer will find useful are those that manipulate the shape hierarchy and provide support for archiving a shape and all of the resources that the shape needs.  Other methods (cursor management, color management, surface type management) are provided as a convenience feature.

Another advantage to providing the header file to the Camera class is that it greatly eases the debugging of loadable modules.  Since an instance of camera is almost always in the responder chain when dealing with a loadable bundle, FirstResponder methods can be added to the Camera class (or to the Window class, for a more general responder chain method) via the implementation of a Camera category.  More information can be found in the documentation on the loadable debugging module (3DDebugUtilities).

Instance Variables

int	currSurface
int	fidelity
float	shadingRate
float	worldScale
float	grid
RtColor	selectColor
RtColor	unselectColor
struct _caFlags {
	unsigned int trackingUserAction:1;	unsigned int drawSelectionMarks:1;	unsigned int dontDrawSlaves:1;
	unsigned int cropToSelectionRect:1;	unsigned int projectionPosition:3;
	unsigned int gridActive:1;
	unsigned int gridVisible:1;
	unsigned int allSelected:1;
	unsigned int useUnSelectColor:1;
	unsigned int locationNumber:5;	unsigned int ignoreFiles:1;
} caFlags;
NXDataLinkManager	*linkManager
id	constraintsManager
id	tracker
id	cursor
List	*locationList
id	image
NXPoint	imageOrigin
id	_private2
NXRect	_selectRect

currSurface	current surface type used for screen rendering
fidelity	number of facets used during screen rendering
shadingRate	shading rate used for photo realistic rendering
worldScale	scale factore for various location variables throughout UI
grid	reserved for future implementation
selectColor	color used for screen rendering of selected objects
unselectColor	color used for screen rendering of unselected shapes that don't have a color
caFlags.trackingUserAction	YES if currently tracking an event
caFlags.drawSelectionMarks	reserved
caFlags.dontDrawSlaves	YES if camera's dispaly method triggers a redisplay of it's slaves
caFlags.cropToSelectionRect	if YES, RIB output will be cropped to _selectRect
caFlags.projectionPosition	projection position selector
caFlags.gridActive	reserved
caFlags.gridVisible	reserved
caFlags.allSelected	YES if all shapes are currently selected
caFlags.useUnSelectColor	YES if camera should use unselect color when screen rendering
caFlags.locationNumber	current camera location index
caFlags.ignoreFiles	YES if camera should ignore any files being created-- used for resource management
linkManager	hot link manager
constraintsManager	Camera's constraints engine
tracker	Camera's event tracking engine
cursor	current cursor used in camera's window
locationList	list of named locations defined for this camera
image	background image used in camera
imageOrigin	origin of the background image within the camera's 2D coordinate system
_private2	reserved
_selectRect	current selection rectangle used during selection rendering

Method Types

Class Management	+ currentCamera

Initialization	- initFrame:

Selection Color	- setSelectColor
- setUnSelectColor
- useUnSelectColor
- setUseUnSelectColor

Hierarchy Management	- addObject:
- connectShape:to:
- connectShape:
- connectShapeAndDisplay:
- deletShape:

Selection Management	- selectAll:
- deselectAll:
- selectedShape
- anySelectedShape
- selectShape:andDisplay:updateBrowser:
- selectShape:andDisplay:
- selectShape:
- getSelectedShapes:
- setSelectedShapes:

Shape Position	- moveShape:to:
- shapeAt:

Surface Type	- setRenderTypeTemporarily:shape:
- setRenderTypeTemporarily:
- restoreRenderType

UI Update	- updateBrowserAndInspector

Archiving Support	+ writeShape:toStream:
+ readShapeFromStream:
- write:
- read:
- awake

Cursor	- setCursor:

Count	- shapeCount
- selectedCount

Class Methods

currentCamera
+ currentCamera

Returns the currently active camera.  It first checks to see if the key window contains a camera, if it doesn't find a camera in that window, it then searches the Application's window list for the top most camera.

readShapeFromStream:
+ (Shape *) readShapeFromStream:(NXStream *) stream

Reads and returns a shape from stream.  This method also makes sure that any of the resources that might need to be dynamically loaded before the shape is read are available.

See also:  writeShape:toStream:

writeShape:toStream:
+ writeShape:(Shape *) shape toStream:(NXStream *) stream

Writes shape to stream.  Resulting stream should be decomposed by using readShapeFromStream: to make sure that any resources needed by the shape are loaded and available.  The resource information is in the form of an archived list.

See also:  readShapeFromStream:

Instance Methods

addObject:
- (Shape *) addObject:newObject

Sets newObject to be selectable and visible.  Also sets the surface type to be the current surface type of the camera.  It then calls connectShape: to actually add the shape to the hierarchy.  Does not redisplay camera. Returns newObject.

See also:  connectShape:

anySelectedShape
- (Shape *) anySelectedShape

Calls selectedShape to find the camera's currently selected shape.  If selectedShape returns nil, then the world shape is returned.

See also:  selectedShape

connectShape:to:
- connectShape:(Shape *) shape to:(Shape *) connectShape

Adds shape to the camera's shape hierarchy as a descendant or peer to connectShape.  If connectShape is the camera's world shape, then shape is added as the last peer of world shape's descendant.  Once the shape has been added to the hierarchy, this method calls shape's wasAddedTo: method (if shape responds to wasAddedTo:) Does not redisplay camera.

connectShape:
- connectShape:(Shape *) shape

Calls connectShape:to: with the connectShape being the result of a call to anySelectedShape.  This method is used whenever a shape is dragged and dropped onto the camera.

See also:  connectShape:to:

connectShapeAndDisplay:
- connectShapeAndDisplay:(Shape *) shape

Calls connectShape:to: wiht the connectShape being the result of a call to anySelectedShape.  This method then notifies the connectShape that shape was connected via the shapesConnected: method (if shape implements it).  Shape is then selected via selectShape:

See also:  connectShape:to:

deleteShape:
- deleteShape:(Shape *) shape

Unlinks the shape from the hierarchy, calls updateBrowserAndInspector and then redisplays the camera.

deselectAll
- deselectAll:sender

This method deselects all shapes in the camera's shape hierarchy.  It also redisplays the camera if the sender is not the camera.  Returns self.

See also:  selectAll:

displayOnlySelf
- displayOnlySelf

Sends a display message to the camera, and not the slaves.

See also:  drawSlaves

drawSlaves
- drawSlaves

Draws all cameras related to self by sending a displayOnlySelf message to each camera.  If self is an instance of the CameraSlave class, then the master camera is redisplayed via displayOnlySelf as well (but self is never redisplayed).

See also:  displayOnlySelf

getSelectedShapes:
- getSelectedShapes:(List *) sList

Fills sList with all of the shapes that are marked as being selected.  If sList is nil, this method will allocate a new list (from the default zone).  Always returns sList.  Though this method exists, there is no user interface or support for dealing with multiple shape selections-- that will be supported in a future version of the product.

See also:  setSelectedShapes:

initFrame
- initFrame: (const NXRect *) frameRect

The designated initializer for the Camera class.

moveShape:to:
- moveShape:(Shape *) aShape to:(NXPoint *) p

Translates aShape to a point on the plane of action (the plane defined by the origin of aShape's ancestor and the surface normal defined by the eye point to view point vector).  To choose the point on the plane of action, p is first converted to a set of near-far points (see N3DShape's convertPoints:count:toWorld) and the intersection between the segment defined by the near-far points and the plane of action.  aShape is translated by grabbing its transform matrix and setting the translation directly in that matrix.

See also:  shapeAt:

restoreRenderType
- restoreRenderType

If setRenderTypeTemporarily: or setRenderTypeTemporarily:shape: has been called recently, this method will restore the surface rendering type to whatever it was before that call was made.

See also:  setRenderTypeTemporarily:,
			 setRenderTypeTempoerarily:shape:

selectAll:
- selectAll:

Selects all of the shapes in the camera's hierarchy and redisplays the camera if the sender is not the camera.

See also:  deselectAll:

selectShape:
- selectShape:(Shape *) aShape

This method calls selectShape:andDisplay:updateBrowser:.  Both the andDisplay: and the updateBrowser: arguments are YES.

See also:  selectShape:andDisplay:updateBrowser:

selectShape:andDisplay:
- selectShape:(Shape *) aShape andDisplay:(BOOL) flag

This method calls selectShape:andDisplay:updateBrowser:.  The updateBrowser: argument is YES.

See also:  selectShape:andDisplay:updateBrowser:

selectShape:andDisplay:updateBrowser:
- selectShape:(Shape *) aShape
           andDisplay:(BOOL) flag
	   	     updateBrowser:(BOOL) otherFlag

First deselects all of the shapes via the deselectAll: method.  This method then selects aShape and updates the inspector panel.  If flag is YES, then the camera redisplays itself (and any slaves).  If otherFlag is YES, then the browser updates itself by showing the path to aShape.

selectedCount
- (int) selectedCount

Returns the number of shapes currently selected.

selectedShape
- (Shape *) selectedShape

Returns the currently selected shape or nil if no shape is currently selected

See also:  getSelectedShapes:

setCursor:
- setCursor:aCursor

Sets the cursor for the camera to be aCursor.  If aCursor is nil, then the cursor is set to the NXArrow.

setRenderTypeTemporarily:
- setRenderTypeTemporarily:(int) surface

This is a cover method for setRenderTypeTemporarily:shape:, that sets the rendering style for all shapes within the hierarchy.

See also:  setRenderTypeTemporarily:shape:

setRenderTypeTemporarily:shape:
-  setRenderTypeTemporarily:(int) surface shape:(Shape *)shape

Sets the surface rendering type to surface until restoreRenderType is called (or the user selects a new surface type within the UI).  Possible surface types are:
		N3D_PointCloud
		N3D_WireFrame
		N3D_ShadedWireFrame
		N3D_FacetedSolids
		N3D_SmoothSolids
This method also automatically chooses the hider used by the rendering engine.

setSelectColor
- setSelectColor

Calls RiSetColor() to set the current rendering color to the selected color.

See also:  setUnSelectColor

setSelectedShapes:
- setSelectedShapes:(List *) sList

Deselects all shapes (via deselectAll:) and the walks down sList, sending each shape a setSelected: method.  It then updates the inspector window.  Though this method exists and works, there is no support for dealing with multiple shape selections.

See also:  getSelectedShapes:

setUnSelectColor
- setUnSelectColor

Calls RiSetColor() to set the current rendering color to the unselected color

See also:  setSelectColor

shapeAt:
- (Shape *) shapeAt:(const NXPoint *) viewPoint

Finds the first shape that lies underneath viewPoint via a depth first traversal.  Returns the shape found or nil if there is no shape under viewPoint.

See also:  moveShape:to:

shapeCount
- (int) shapeCount

Returns the number of shapes that exist in the camera's hierarchy (not including the world shape).

See also:  selectedCount

updateBrowserAndInspector
- updateBrowserAndInspector

Updates both the hierarchy browser and the inspector to reflect the currently selected shape within the camera's hierarchy.

useUnSelectColor
- (BOOL) useUnSelectColor

Returns YES if the camera will screen render shapes using the unselected color.